…ral closure)

Closes the third explicit defer from PR #135 (Avenue A v2). An Explore-agent
investigation traced Skills' code-execution registration path at
src/server/legacyStreamHandler.js:78 and reached a decisive DOCUMENT-NO-CHANGE
verdict: Avenue A v2 deliberately does NOT apply to Skills.

═══════════════════════════════════════════════════════════════════════
RATIONALE
═══════════════════════════════════════════════════════════════════════

The codebase has TWO independent code-execution surfaces against Anthropic
Messages API:

  Bridge        (src/tools/codeExecutionBridge.js:30)
  ───────────────────────────────────────────────────
    Tool:      code_execution_20260120
    Pattern:   Orchestrator-driven multi-turn with envelope contract
    Validate:  isCompleteXlsxB64, selectEnvelopeWithFallback
    Retry:     MAX_TURNS=3 corrective loop
    Avenue A v2: APPLIED (output_config + json_schema enforcement)

  Skills (native)  (src/server/legacyStreamHandler.js:78)
  ───────────────────────────────────────────────────────
    Tool:      code_execution_20250825
    Pattern:   Single-turn streaming pass-through to frontend
    Validate:  None — free-form text + tool_use_result blocks
    Retry:     None (terminal failure on malformed output)
    Avenue A v2: NOT APPLICABLE

Skills doesn't exhibit the envelope-miss failure mode Avenue A v2 fixed because
Skills HAS NO ENVELOPE CONTRACT to enforce. Skills output is free-form text
accumulated and streamed to caller; there's no schema, no validation, no retry.

═══════════════════════════════════════════════════════════════════════
WHY output_config ENFORCEMENT WOULD ACTIVELY HARM SKILLS
═══════════════════════════════════════════════════════════════════════

1. CONFLICT with existing outputFormatSchema logic at lines 112-115:
   output_config: { effort: 'high', ...(outputFormatSchema ? {format}: {}) }
   Adding ...(skills ? {format: skillsSchema} : {}) creates duplicate `format`
   key — JS uses the LAST one, silently overwriting user-requested structured
   output enforcement.

2. NO downstream parsed_output consumer:
   - Bridge reads response.parsed_output (codeExecutionBridge.js:extractResults)
   - legacyStreamHandler streams text + tool_use_result only — never inspects
     parsed_output
   - Structured output would be generated + billed in tokens but ignored

3. TRUNCATION RISK worse than xlsx's:
   - Skills outputs (PDF extracts, document parses, OCR) are often LARGE
   - Skills has NO secondary fallback channel (xlsx had stdout to fall back on)
   - Forced text-channel JSON enforcement could hit max_tokens cliff with NO
     architectural mitigation — re-introduces the L4 v1 failure mode

═══════════════════════════════════════════════════════════════════════
SKILLS IS ARCHITECTURAL DEAD CODE IN PROD
═══════════════════════════════════════════════════════════════════════

Four independent signals:

  1. SKILLS_ENABLED=false in flags.env:62 (production default)
  2. USE_AGENT_SDK=true in flags.env (production default) — routes /api/stream
     to handleAgentStream, NOT handleLegacyStream. Skills path never invoked
     in production even hypothetically.
  3. Architectural pivot commit 1200048: "Step 3 — absorb Anthropic xlsx
     Skill content into bridge prompt" — deliberately moved xlsx skill
     functionality INTO the bridge, replacing Skills-API approach
  4. Code comment in featureFlags.js:14-17 explicitly states "Custom skills
     disabled: Non-SDK-compliant format with no-op code"

═══════════════════════════════════════════════════════════════════════
DELIVERABLE
═══════════════════════════════════════════════════════════════════════

This PR is documentation-only:

  docs/code-execution-enhancements/anthropic-sdk-best-practices-research.md
    +§12 "Skills' parallel code-execution path: why Avenue A v2 does NOT
    apply (2026-05-16 investigation)" — includes bridge-vs-Skills output-
    contract comparison table for future reference

  CHANGELOG.md
    [Unreleased] entry under "Documented" — closes follow-up #3 with the
    architectural posture rationale

═══════════════════════════════════════════════════════════════════════
FUTURE DIRECTION
═══════════════════════════════════════════════════════════════════════

If custom skills become SDK-compliant in the future, re-evaluate under
Programmatic Tool Calling (PTC) using code_execution_20260120 +
allowed_callers. At that point, Avenue A v2-style enforcement could be
applied at that distinct surface. Until then, Skills remains a deprecated
pass-through; bridge remains the canonical structured-output surface.

═══════════════════════════════════════════════════════════════════════
STACKED ON PR #136
═══════════════════════════════════════════════════════════════════════

This branch is stacked on feature/codeexec-avenue-a-v2-telemetry-docs (PR
#136) so the §12 addition cleanly follows the §11 (empirical constraints)
content added there. When PR #136 merges to main, this PR will need to be
rebased onto main; the rebase is conflict-free since §12 is purely additive
to the end of the doc file.

VERIFICATION:
  Suite: 202/0/2 (PR #136's baseline maintained; no code change in this PR)

ROLLBACK: trivial — `git revert <merge-sha>` removes the doc additions.
No code, schema, or behavior implications.

Plan: /Users/ej/.claude/plans/glittery-toasting-stardust.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>